SPI HAL driver

The section describes the programming interface of the SPI HAL driver. More...

Data Structures
struct	spi_config_t
	SPI hardware configuration settings. More...

Enumerations
enum	spi_status_t {   kStatus_SPI_Success = 0,   kStatus_SPI_SlaveTxUnderrun,   kStatus_SPI_SlaveRxOverrun,   kStatus_SPI_Timeout,   kStatus_SPI_Busy,   kStatus_SPI_NoTransferInProgress }
	Error codes for the SPI driver. More...
enum	spi_master_slave_mode_t {   kSpiMaster = 1,   kSpiSlave = 0 }
	SPI master or slave configuration. More...
enum	spi_clock_polarity_t {   kSpiClockPolarity_ActiveHigh = 0,   kSpiClockPolarity_ActiveLow = 1 }
	SPI clock polarity configuration. More...
enum	spi_clock_phase_t {   kSpiClockPhase_FirstEdge = 0,   kSpiClockPhase_SecondEdge = 1 }
	SPI clock phase configuration. More...
enum	spi_shift_direction_t {   kSpiMsbFirst = 0,   kSpiLsbFirst = 1 }
	SPI data shifter direction options. More...
enum	spi_ss_output_mode_t {   kSpiSlaveSelect_AsGpio = 0,   kSpiSlaveSelect_FaultInput = 2,   kSpiSlaveSelect_AutomaticOutput = 3 }
	SPI slave select output mode options. More...
enum	spi_pin_mode_t {   kSpiPinMode_Normal = 0,   kSpiPinMode_Input = 1,   kSpiPinMode_Output = 3 }
	SPI pin mode options. More...

Configuration
void	spi_hal_init (uint32_t instance, const spi_config_t *config)
	Configures the SPI peripheral.
void	spi_hal_reset (uint32_t instance)
	Restores the SPI to reset the configuration.
static void	spi_hal_enable (uint32_t instance)
	Enables the SPI peripheral.
static void	spi_hal_disable (uint32_t instance)
	Disables the SPI peripheral.
void	spi_hal_set_baud (uint32_t instance, uint32_t kbitsPerSec)
	Sets the SPI baud rate in kilobits per second.
static void	spi_hal_set_baud_divisors (uint32_t instance, uint32_t prescaleDivisor, uint32_t rateDivisor)
	Configures the baud rate divisors manually.
static void	spi_hal_set_master_slave (uint32_t instance, spi_master_slave_mode_t mode)
	Configures the SPI for master or slave.
void	spi_hal_set_slave_select_output_mode (uint32_t instance, spi_ss_output_mode_t mode)
	Sets how the slave select output operates.
void	spi_hal_set_data_format (uint32_t instance, spi_clock_polarity_t polarity, spi_clock_phase_t phase, spi_shift_direction_t direction)
	Sets the polarity, phase, and shift direction.
void	spi_hal_set_pin_mode (uint32_t instance, spi_pin_mode_t mode)
	Sets the SPI pin mode.

DMA
void	spi_hal_configure_dma (uint32_t instance, bool enableTransmit, bool enableReceive)
	Configures the transmit and receive DMA requests.

Low power
static void	spi_hal_configure_stop_in_wait_mode (uint32_t instance, bool enable)
	Enables or disables the SPI clock to stop when the CPU enters wait mode.

Interrupts
static void	spi_hal_enable_receive_and_fault_interrupt (uint32_t instance)
	Enables the receive buffer full and mode fault interrupt.
static void	spi_hal_disable_receive_and_fault_interrupt (uint32_t instance)
	Disables the receive buffer full and mode fault interrupt.
static void	spi_hal_enable_transmit_interrupt (uint32_t instance)
	Enables the transmit buffer empty interrupt.
static void	spi_hal_disable_transmit_interrupt (uint32_t instance)
	Disables the transmit buffer empty interrupt.
static void	spi_hal_enable_match_interrupt (uint32_t instance)
	Enables the match interrupt.
static void	spi_hal_disable_match_interrupt (uint32_t instance)
	Disables the match interrupt.

Status
static bool	spi_hal_is_read_buffer_full (uint32_t instance)
	Checks whether the read buffer is full. More...
static bool	spi_hal_is_transmit_buffer_empty (uint32_t instance)
	Checks whether the transmit buffer is empty. More...
static bool	spi_hal_is_mode_fault (uint32_t instance)
	Checks whether a mode fault occurred.
void	spi_hal_clear_mode_fault (uint32_t instance)
	Clears the mode fault flag.
static bool	spi_hal_is_match (uint32_t instance)
	Checks whether the data received matches the previously-set match value.
void	spi_hal_clear_match (uint32_t instance)
	Clears the match flag.

Data transfer
static uint8_t	spi_hal_read_data (uint32_t instance)
	Reads a byte from the data buffer.
static void	spi_hal_write_data (uint32_t instance, uint8_t data)
	Writes a byte into the data buffer.

Match byte
static void	spi_hal_set_match_value (uint32_t instance, uint8_t matchByte)
	Sets the value which triggers the match interrupt.

---

Data Structure Documentation

struct spi_config_t

Use an instance of this structure with spi_hal_init(). This allows you to configure the

most common settings of the SPI peripheral with a single function call.

The kbitsPerSec member is handled separately. If this value is set to 0, then the baud is

not set by spi_hal_init(), and must be set with a separate call to either the spi_hal_set_baud()

or the spi_hal_set_baud_divisors(). This can be useful if you know the divisors in advance and

don't want to spend the time to compute them for the provided rate in kilobits/sec.

Data Fields
bool	isEnabled
	Set to true to enable the SPI peripheral. More...
uint32_t	kbitsPerSec
	Baud rate in kilobits per second. More...
spi_master_slave_mode_t	masterOrSlave
	Whether to put the peripheral in master or slave mode. More...
spi_clock_polarity_t	polarity
	Clock polarity setting. More...
spi_clock_phase_t	phase
	Clock phase setting. More...
spi_shift_direction_t	shiftDirection
	Direction in which data is shifted out. More...
spi_ss_output_mode_t	ssOutputMode
	Output mode for the slave select signal. More...
spi_pin_mode_t	pinMode
	Pin mode with bidirectional option. More...
bool	enableReceiveAndFaultInterrupt
	Enable for the receive and fault interrupt. More...
bool	enableTransmitInterrupt
	Enable for the transmit interrupt. More...
bool	enableMatchInterrupt
	Enable for the match interrupt. More...

Field Documentation

bool spi_config_t::isEnabled

uint32_t spi_config_t::kbitsPerSec

spi_master_slave_mode_t spi_config_t::masterOrSlave

spi_clock_polarity_t spi_config_t::polarity

spi_clock_phase_t spi_config_t::phase

spi_shift_direction_t spi_config_t::shiftDirection

spi_ss_output_mode_t spi_config_t::ssOutputMode

spi_pin_mode_t spi_config_t::pinMode

bool spi_config_t::enableReceiveAndFaultInterrupt

bool spi_config_t::enableTransmitInterrupt

bool spi_config_t::enableMatchInterrupt

Enumeration Type Documentation

enum spi_status_t

Enumerator
kStatus_SPI_SlaveTxUnderrun	SPI Slave TX Underrun error.
kStatus_SPI_SlaveRxOverrun	SPI Slave RX Overrun error.
kStatus_SPI_Timeout	SPI transfer timed out.
kStatus_SPI_Busy	SPI instance is already busy performing a transfer.
kStatus_SPI_NoTransferInProgress	Attempt to abort a transfer when no transfer was in progress.

enum spi_master_slave_mode_t

Enumerator
kSpiMaster	SPI peripheral operates in master mode.
kSpiSlave	SPI peripheral operates in slave mode.

enum spi_clock_polarity_t

Enumerator
kSpiClockPolarity_ActiveHigh	Active-high SPI clock (idles low).
kSpiClockPolarity_ActiveLow	Active-low SPI clock (idles high).

enum spi_clock_phase_t

Enumerator
kSpiClockPhase_FirstEdge	First edge on SPSCK occurs at the middle of the first cycle of a data transfer.
kSpiClockPhase_SecondEdge	First edge on SPSCK occurs at the start of the first cycle of a data transfer.

enum spi_shift_direction_t

Enumerator
kSpiMsbFirst	Data transfers start with most significant bit.
kSpiLsbFirst	Data transfers start with least significant bit.

enum spi_ss_output_mode_t

Enumerator
kSpiSlaveSelect_AsGpio	Slave select pin configured as GPIO.
kSpiSlaveSelect_FaultInput	Slave select pin configured for fault detection.
kSpiSlaveSelect_AutomaticOutput	Slave select pin configured for automatic SPI output.

enum spi_pin_mode_t

Enumerator
kSpiPinMode_Normal	Pins operate in normal, single-direction mode.
kSpiPinMode_Input	Bidirectional mode. Master: MOSI pin is input; Slave: MISO pin is input
kSpiPinMode_Output	Bidirectional mode. Master: MOSI pin is output; Slave: MISO pin is output

Function Documentation

static bool spi_hal_is_read_buffer_full ( uint32_t  instance )

inlinestatic

The read buffer full flag is only cleared by reading it when it is set, then reading the data register by calling the spi_hal_read_data(). This example code demonstrates how to check the flag, read data, and clear the flag.

*      // Check read buffer flag.
*      if (spi_hal_is_read_buffer_full(0))
*      {
*          // Read the data in the buffer, which also clears the flag.
*          byte = spi_hal_read_data(0);
*      }
* 

static bool spi_hal_is_transmit_buffer_empty ( uint32_t  instance )

inlinestatic

To clear the transmit buffer empty flag, you must first read the flag when it is set. Then write a new data value into the transmit buffer with a call to the spi_hal_write_data(). The example code shows how to do this.

*      // Check if transmit buffer is empty.
*      if (spi_hal_is_transmit_buffer_empty(0))
*      {
*          // Buffer has room, so write the next data value.
*          spi_hal_write_data(0, byte);
*      }
*